home *** CD-ROM | disk | FTP | other *** search
/ User's Choice Windows CD / User's Choice Windows CD (CMS Software)(1993).iso / win_m_p / paswin31.zip / MIXAPI.DOC < prev    next >
Text File  |  1992-06-08  |  38KB  |  1,100 lines
  1.  
  2.  
  3.         Proposed Specification for MIXER API
  4.          copyright Media Vision (c) 1991
  5.            version 0.6b -- Ken Nicholson
  6.  
  7.               
  8.  
  9. MCIMIXER.DRV    MCI interface to the mixer driver
  10. MMMIXER.DLL      Multimedia Mixer DLL
  11. MVMIXER.DRV    Media Vision Mixer driver
  12.  
  13.  
  14. THE MULTIMEDIA MIXER DLL
  15.  
  16. The Multimedia Windows Mixer DLL, as proposed by Media Vision, is a
  17. library of generalized routines that provides a common,    device-independent
  18. interface to software controllable mixers.  Its design is based on the uses
  19. and functionality of real world audio mixers.
  20.  
  21. This DLL gives the MultiMedia application programmer control over a complete
  22. range of audio capabilites.  Every conceivable audio mixing, patching,
  23. equalization and amplification need can be handled by this DLL and its API.
  24. It is capable of supporting mixing features far beyond those available
  25. with today's PC hardware.
  26.  
  27.  
  28. WHY A MULTIMEDIA MIXER ?
  29.  
  30. The Multimedia PC Specification version 1 (May 13,1991) calls for 
  31. "On-board analog audio mixing capabilities," requiring "... input
  32. from three (recommended four) sources and [must] present the sources as
  33. a stereo, line-level audio signal at the back panel. ... Individual
  34. audio source and master digital volume control registers and extra
  35. line-level audio sources are highly recommended."
  36.  
  37. Such hardware requires a set of standard functions calls (API's) that
  38. will handle volume changes in a device-independent and extensible way.
  39. Furthermore, there are a number of issues, apart from the setting of
  40. an input's or an output's volume levels, that should be handled in a
  41. standard way.  Functions such as equalization, special effects, patch
  42. changes, device association, connection mapping, smooth timed transitions,
  43. power-up settings and device sharing were not addressed by the November Beta
  44. release of the Multimedia Windows Development Kit.
  45.  
  46. What is provided? The WAVEOUT and MIDIOUT drivers have Get- and SetVolume
  47. entry points for control of a device's output volume.  In addition, the
  48. Multimedia Extensions define an AUX device type that allows
  49. applications to get and set the volumes of additional devices.  The
  50. only two types of AUX devices defined are CD audio and auxillary
  51. input.
  52.  
  53. In the current design of the Multimedia Extensions, there is no link
  54. between an AUX device and the audio device associated with it.  It
  55. may be assumed, when there is only one AUX device, that it controls
  56. the audio output of the CD-ROM drive.  But in the presence of multiple
  57. AUX devices there is no mechanism for an application to determine 
  58. which AUX device to control to change the CD volume.  Varying
  59. AUX-to-Device association will cause chaos for application writers.
  60.  
  61. This raises the question of volume control for devices in general.
  62. Most consumer audio devices (cassette decks, turntables, video disk
  63. players, televisions) don't have a variable line output. These
  64. devices rely on a mixer or integrated amplifier to control the volume
  65. level.  The term "attenuator" is applied to controls that vary the
  66. line output of a device. 
  67.  
  68. Attenuation of PCM and MIDI audio output is not something users need
  69. concern themselves with and therefore volume control functions do not
  70. belong in waveout and midiout drivers; volume control is properly a
  71. mixing function.  Users and multimedia authors will want to individually
  72. adjust the relative volumes of a number of device outputs and this is the
  73. primary need for a mixer.  The Mixer API solves this problem by supporting
  74. volume controls on each of any number of mixer inputs as well supporting
  75. volume controls for each mixer output.
  76.  
  77. Some professional audio mixers feature a myriad of knobs to enhance or
  78. alter input audio.  Among these are controls for bass, midrange and treble, 
  79. controls to add reverb, effects and stereo-mono crossover.  In fact, Media
  80. Vision's Pro-Audio Spectrum supports many of these features.  The
  81. existing Multimedia Windows API's don't address these features.
  82.  
  83. Another feature of the MMMIXER.DLL API set is its ability to maintain and
  84. coordinate mixer patch information.  A mixer device that supports
  85. software selectable input patching would allow any one of several audio
  86. devices to be "patched" to a mixer input.  Similarly an application
  87. can interrogate the mixer API to find out which devices are connected
  88. to which mixer inputs.
  89.  
  90. Fading the volume up of one sound source while fading out the volume
  91. of another seems such an intrinsically necessary function for multimedia
  92. that we have incorporated it into the DLL.  Without this feature, the
  93. application programmer would be required to send auxSetVolume
  94. messages in "ping-pong" fashion to the devices to be cross-faded.
  95.  
  96. Some users will have powered speakers with no volume control. MMWindows
  97. start-up sounds are capable of producing DEAFENING DECIBELS OF DIN. 
  98. Mixer drivers conforming to this spec read WIN.INI to determine the
  99. desired start-up, or mixer reset, volume settings.
  100.  
  101. Frequently an application will fill the entire screen and on occasion
  102. a Multimedia application will suprise the user with unexpectedly loud
  103. audio.  Such moments find the user frantically trying to bring up the
  104. volume control application in order to lower the volume.  An equally 
  105. dismaying situation is starting a multimedia application only to
  106. discover that the volumes are too low for the sound to be audible.
  107. The MMMIXER.DLL intercepts the CTRL-ALT-U and CTRL-ALT-D sequences
  108. and translates them into driver volume up and down calls.  This
  109. allows the user to quickly change volumes up and down.
  110.  
  111. Media Vision has developed the Multimedia Windows DLL to address these and
  112. other issues in audio control on the MPC.  We gratefully acknowledge 
  113. Microsoft and especially the members of the Multimedia Windows
  114. Development Team for their advice and assistance in developing the
  115. Multimedia Mixer DLL and the Media Vision Mixer driver.
  116.                         
  117.  
  118. MEDIA VISION IMPLEMENTATION
  119.  
  120. The Multimedia Mixer DLL is capable of supporting virtually any type
  121. of mixing hardware.  The limitations of the Pro AudioSpectrum mixing 
  122. hardware should not be confused with the capabilities of the
  123. Multimedia Mixer DLL.
  124.  
  125. MVMIXER.DRV is implemented as a single Mixer device.  This mixer has
  126. seven input lines and two output lines.  The Pro AudioSpectrum 16 has
  127. new mixer circuitry that allows 8 input lines.
  128.  
  129. The standard input lines are by default patched to:
  130. 1) FM SYNTHESIZER          5) MICROPHONE
  131. 2) RECORD MONITOR              6) WAVE (PCM)
  132. 3) AUXILLARY INPUT          7) PC speaker
  133. 4) INTERNAL CD              8) Snd Blaster WAVE (mono PCM)    
  134.  
  135. On the Pro AudioSpectrum and Pro AudioSpectrum Plus, Input #2 is the mix
  136. of all devices being routed to Output #2.  For the Pro AudioSpectrum 16,
  137. Input #2 becomes a second internal CD connector.
  138.  
  139. Each input can be connected to one (but not both) of the two outputs.
  140. 1) PLAY      (Line Out)
  141. 2) RECORD (Wave In)
  142.  
  143. Output #1, apart from supporting volume control, supports treble and
  144. bass, loudness, stereo enhance and mute.
  145. Output #2  supports volume control on the Pro-16 only.      
  146.  
  147. Input #2 should not be patched to Output #2. 
  148. Input #6 should be patched to Output #2 during playback for proper
  149. waveform filtering.  This is only necessary on the 8-bit Pro
  150. AudioSpectrum.
  151.  
  152. mixGetDevCaps returns the following structure:
  153.     
  154. MIXERCAPS MVMixer= {
  155.     MM_MEDIAVISION,             // manufacturer id
  156.     MM_PROAUD_MIXER,        // product id
  157.     (VERSION) 0x100,          // version of the driver
  158.     "Pro AudioSpectrum",    // product name (NULL terminated string)
  159.     7,                // number of inputs  supported.
  160.     2,                // number of outputs supported.
  161.     9,                 // number of input patches supported.
  162.     3,                // number of output patches supported.
  163.     MIXERCAP_MANUALPATCHSWITCH,    // supports some manual   patching
  164.     NULL            // reserved
  165.     };
  166.  
  167.  
  168.  
  169. A Line Capabaility structure for the Pro Audio Spectrum Mixer
  170. would look like this:
  171. {
  172. wNumber        =0;              // This is the current caps for input # 0
  173. dwDeviceType=MIX_MICROPHONE    // Microphone currently patched;
  174.         +MIX_USER_CONNECTED;// Requires user to plug it in (for prompting)
  175. wNumSoftPatches=1;           // This input always patched to the Microphone
  176. wPatchNumber=0;               // the only mic
  177. wNumChannels=2;               // The mic is actually mono with a splitter
  178. dwSupport   =MIX_SUPPORT_LRVOLUME    // supported functionality 
  179. szIOname    ="Line 1: Microphone Jack"    // Input Name
  180. szPname     ="MIC";              // patch name 
  181. }
  182.  
  183.  
  184.  
  185. Each Mixer has a built in number of INPUT and OUTPUT patches. They
  186. are referenced by an ordinal number starting from zero.  Patch number
  187. zero is always defined as NO CONNECT.
  188.  
  189. Here is the capability structure for Output #1:
  190.  
  191. {
  192. wPatchNumber =1;                // This patch's ordinal number
  193. dwDeviceType =MIX_AMPLIFIER|      // device connected is amplifier
  194.           MIX_LISTENER|      // all output patches are listeners
  195.               MIX_USER_CONNECTED; // requires a cable connection
  196. dwLineNumbers=1<<0;           // bit-field, lines connectable to
  197. szPname[]    ="MASTER";          // patch name (NULL terminated string)
  198. dwAssociation=NULL;             // HIWORD=type, LOWORD=device
  199. dwReserved1  =NULL;              // reserved for future use
  200. } 
  201.  
  202.  
  203.  
  204. //////////////////////////////////////////////////////////////////////
  205. //////////////////////////////////////////////////////////////////////
  206.  
  207.  
  208.                 MIXER API OVERVIEW
  209.  
  210.  
  211.  
  212. MIXER GENERAL FUNCTIONS:
  213.  
  214. mixGetNumDevs         - returns the number of mixer devices
  215. mixGetDevCaps         - provides information on mixer device capability
  216. mixOpen         - opens mixer device
  217. mixClose        - closes mixer device
  218. mixGetErrorText     - gets a text string corresponding to error number
  219.  
  220. MIXER PRESET FUNCTIONS:
  221.  
  222. mixReset        - resets mixer inputs, volumes, patches etc.
  223. mixGetState         - gets current state of the mixer device
  224. mixSetState        - sets mixer state with optional timed fade
  225. mixGetFadeStatus    - returns time remaining of current fadeprocess
  226.  
  227. // INPUT TO OUTPUT CONNECTION 
  228.  
  229. mixGetConnections    - gets the connection map of an input or output
  230. mixSetConnections    - sets input to output connection map
  231.  
  232. // LINE CONTROLS
  233. mixGetControl        - gets the setting of a line's control
  234. mixSetControl        - sets the level of a line's control
  235. mixGetLineInfo        - gets functionality and current status of a line
  236.  
  237. // PATCH CALLS
  238. mixGetPatch        - gets a line's patch number
  239. mixSetPatch        - sets a line's patch information
  240. mixGetPatchInfo        - returns information on a standard mixerpatch
  241.  
  242. // DEVICE ORIENTED CALLS
  243. mixGetDeviceName    - converts device type to device name
  244. mixGetDeviceLines    - finds which lines have a specified device 
  245. mixSetDeviceConnections    - performs abstract device connection
  246. mixGetDeviceConnections - determines device types connected
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253. MIXER DEVICE GENERAL FUNCTIONS
  254.  
  255. mixGetNumDevs         - returns the number of mixer devices
  256. mixGetDevCaps         - provides information on mixer device capability
  257. mixOpen         - opens mixer device
  258. mixClose        - closes mixer device
  259. mixGetErrorText     - gets a text string corresponding to error number
  260.  
  261.  
  262. ______________________________________________________________________
  263.  
  264.  
  265. Syntax        WORD mixGetNumDevs(void)
  266.         This function retrieves the number of mixer devices
  267.         present in the system.
  268.  
  269. Parameters    None
  270.  
  271. Return Value    Returns the number of mixer devices present in the
  272.         system
  273.  
  274. ______________________________________________________________________
  275.  
  276. Syntax        mixGetDevCaps(wDeviceID, lpCaps, wSize)
  277.  
  278. Parameters    WORD  wDeviceID
  279.           Identifies the mixer device to be queried.
  280.  
  281.         LPMIXERCAPS  lpCaps
  282.           Specifies a far pointer to a MIXERCAPS structure. 
  283.           This structure is filled with information about the
  284.           capabilities of the device.            
  285.  
  286.         WORD  wSize    
  287.           Specifies the size of the MIXERCAPS structure.
  288.  
  289. Return Value    When the wDeviceID is non-zero, the return value will
  290.         be MIXERR_NOERR (zero) if the function was successful.
  291.         If wDeviceID is zero, the return value is the size of 
  292.         the drivers MIXERCAPS structure.
  293.  
  294. Comments    Use mixGetDevCaps to determine the number of mixer
  295.         devices present in the system.  The Device ID specified
  296.         by wDeviceID varies from zero to one less than the number
  297.         of devices present. Only wSize bytes(or less of information
  298.         will be copied to the location pointed to by lpCaps.  If
  299.         wSize is 0, nothing will be copied and MMSYSERR_NOERROR is
  300.         returned.
  301.  
  302.  
  303. See Also    mixGetNumDevs
  304. ______________________________________________________________________
  305.  
  306. Syntax        mixOpen(lphMixer, wDeviceID, dwFlags)
  307.         
  308.         This function opens a specified mixer device.
  309.         
  310.  
  311. Parameters    LPHMIXER lphMixer
  312.           Specifies a far pointer to an HMIXER handle.  This
  313.           location is filled with a handle identifying the
  314.           opened mixer device.
  315.         
  316.  
  317.         WORD  wDeviceID
  318.  
  319.         DWORD dwFlags
  320.           Specifies flags for opening the device
  321.  
  322.  
  323. Return Value    Returns zero if the function was successful. 
  324.         Otherwise, it returns an error. 
  325.  
  326. Comments    Use mixOpen before making any control/enquiry calls
  327.         to the mixer driver.
  328.         
  329.  
  330. See Also    mixClose
  331. ______________________________________________________________________
  332.  
  333. Syntax        mixClose(hMixer)
  334.  
  335. Parameters    HMIXER    hMixer
  336.  
  337. Return Value    Returns zero if the function was successful. 
  338.         Otherwise, it returns an error. Possible errors are:
  339.  
  340.         MMSYSERR_INVALHANDLE
  341.            Specified device handle is invalid.
  342.  
  343. See Also    mixOpen
  344. ______________________________________________________________________
  345.  
  346. Syntax        mixGetErrorText(wError, lpText, wSize)
  347.     
  348.         This function retrieves a textual description of the
  349.         error identified by the specified error number.
  350.  
  351. Parameters    WORD  wError
  352.           Specifies the error number.
  353.  
  354.         LPSTR lpText
  355.           Specifies a far pointer to a buffer which is filled
  356.           with the textual error description.
  357.  
  358.         WORD  wSize
  359.           Specifies the length of the buffer pointerd to by
  360.           lpText.
  361.  
  362. Return Value    Returns the length of the string copied to zero if the function was successful. 
  363.           
  364. ______________________________________________________________________
  365.  
  366.  
  367.  
  368.  
  369. MIXER PRESET FUNCTIONS
  370.  
  371. mixReset        - resets mixer inputs, volumes, patches etc.
  372. mixGetState         - gets current state of the mixer device
  373. mixSetState        - sets current state of the mixer device
  374. mixGetFadeStatus    - returns time remaining of current fadeprocess
  375.  
  376.  
  377. ______________________________________________________________________
  378.  
  379. Syntax        mixReset(hMixer)
  380.  
  381.         Resets the mixer to a default state.  The default
  382.         state is read from the WIN.INI file.
  383.  
  384. Parameters    HMIXER    hMixer
  385.           Identifies the mixer device to be reset.
  386.  
  387.  
  388. Return Value    Returns zero if the function was successful. 
  389.         Otherwise, it returns an error.
  390.  
  391. See Also    mixOpen, mixGetSetup, mixSetSetup
  392.  
  393. ______________________________________________________________________
  394.  
  395. Syntax        mixGetState(hMixer, lphMixerState, lpwSize)
  396.  
  397.         Returns a handle to a structure containing the
  398.         current state of the mixer.  The structure is
  399.         defined by the device.
  400.  
  401. Parameters    HMIXER     hMixer
  402.           Identifies the mixer device to be used.
  403.  
  404.         LPHANDLE lphMixerState
  405.           Specifies a far pointer to a handle to where the mixer
  406.           state information is saved.
  407.  
  408.         LPWORD   lpwSize
  409.           Specifies a far pointer to a word where the size of
  410.           the mixer state information is stored.
  411.  
  412.  
  413. Return Value    Returns zero if the function was successful. 
  414.         Otherwise, it returns an error. Possible errors are:
  415.  
  416.         MIXERR_BADMIXERPTR    null pointer to mixer
  417.           
  418. Comments    This function is used to save the current state of 
  419.         the specified mixer device.  
  420.  
  421. See Also    mixSetState
  422. ______________________________________________________________________
  423.  
  424. Syntax        mixSetState(hMixer,lpMixerState,wSize,dwTime,
  425.                 dwFlags,dwCallback);
  426.     
  427.         Restores the mixer to a saved state.
  428.  
  429. Parameters    HMIXER    hMixer
  430.           Identifies the mixer device to be used.
  431.  
  432.         LPMIXERSTATE lpMixerState
  433.           Handle to a mixer state structure as returned by
  434.           the mixGetState function.
  435.  
  436.         WORD    wSize
  437.           Size of the mixer state structure.
  438.  
  439.         DWORD    dwTime
  440.           The high word is delay time in tenths of seconds.
  441.           The low word is the duration of the fade in tenths
  442.           of seconds.  A dwTime value of zero results in an
  443.           instant mixer setting.
  444.  
  445.         DWORD    dwFlags
  446.           MIX_FADE_OVERRIDE    override a fade in progress
  447.         
  448.         DWORD    dwCallback
  449.           Address of a procedure to be called when fade is
  450.           complete.  Note: this has not yet been implemented
  451.  
  452.  
  453. Return Value    Returns zero if the function was successful. 
  454.         Otherwise, it returns an error. Possible errors are:
  455.  
  456.         MIXERR_FADEINPROGRESS    
  457.           
  458.           
  459. Comments    If wSize is not correct, this function will be
  460.         rejected.
  461.  
  462. See Also    mixGetState, mixGetFadeStatus
  463.  
  464. ______________________________________________________________________
  465.  
  466. Syntax        mixGetFadeStatus(hMixer,lpdwTime)
  467.  
  468. Parameters    HMIXER     hMixer
  469.           Identifies the mixer device to be used.
  470.  
  471.         LPDWORD  lpdwTime
  472.           The high word is the delay time remaining in tenths
  473.           of seconds.
  474.           The low word is the fade time remaining in tenths
  475.           of seconds.
  476.           An lpdwTime value of zero indicates no fade is in
  477.           progress.
  478.  
  479. Return Value    Returns zero if the function was successful. 
  480.  
  481. Comments    Status indicators displaying the time remaining of
  482.         a fade may wish to call this function upon receipt of
  483.         any of the following MIXER MESSAGES:
  484.  
  485.           WM_MIX_CONTROLCHANGED      
  486.           WM_MIX_CONNECTIONCHANGED  
  487.           WM_MIX_PATCHCHANGED      
  488.  
  489. See Also     mixSetState
  490.         
  491.  
  492. ______________________________________________________________________
  493.  
  494.  
  495.  
  496.  
  497. // INPUT TO OUTPUT CONNECTION 
  498.  
  499. mixGetConnections    - gets the connection map of an input or output
  500. mixSetConnections    - sets input to output connection map
  501.  
  502. ______________________________________________________________________
  503.  
  504. Syntax        mixGetConnections(hMixer,WORD wLine, LPDWORD lpdwConnections);
  505.  
  506. Parameters    HMIXER     hMixer
  507.           Identifies the mixer device to be used.
  508.  
  509.         WORD      wLine
  510.           The low byte indicates the mixer line to get the
  511.           connections information for.
  512.           The high byte indicates whether the line is an
  513.           input line or an output line. The following 
  514.           macros (equates) are used for the high byte:
  515.               MIX_INPUT    
  516.               MIX_OUTPUT
  517.  
  518.         LPDWORD  lpdwConnections
  519.           A far pointer to a DWORD where the connection
  520.           information is to be stored.  Each bit of the
  521.           double word represents a mixer line.  If the
  522.           bit is 1, wLine is connected to that line.
  523.           For example, assume wLine=0x0000, indicating Input
  524.           Line #1.  If that Input line is connected to Output
  525.           Line #0, bit 0 of *lpdwConnections will be set.
  526.           Logically, connection information can only be
  527.           maintained for a mixer with a maximum of 32 inputs
  528.           and 32 outputs.    
  529.  
  530. Return Value    Returns zero if the function was successful. 
  531.         Possible Errors:
  532.             MIXERR_INVALINPUT        illegal input line    
  533.             MIXERR_INVALOUTPUT       illegal output line 
  534.  
  535. Comments    
  536.  
  537. See Also     mixSetConnections
  538.         
  539.  
  540. ______________________________________________________________________
  541.  
  542.  
  543. Syntax        mixSetConnections(Mixer,WORD wLine, DWORD dwConnections);
  544.  
  545. Parameters    HMIXER     hMixer
  546.           Identifies the mixer device to be used.
  547.                    '
  548.         WORD      wLine
  549.           The low byte indicates the mixer line to get the
  550.           connections information for.
  551.           The high byte indicates whether the line is an
  552.           input line or an output line. The following 
  553.           macros (equates) are used for the high byte:
  554.               MIX_INPUT    
  555.               MIX_OUTPUT
  556.               
  557.         DWORD  dwConnections
  558.           This parameter specifies the connection map for the
  559.           given line of the mixer.  If wLine refers to an
  560.           input Line, the outputs specified by this parameter
  561.           will be connected to that input. Bit 0 refers to
  562.           line 0, bit 1 to line 1, etc.
  563.  
  564.  
  565. Return Value    Returns zero if the function was successful. 
  566.         Possible Errors:
  567.             MIXERR_INVALINPUT        illegal input line    
  568.             MIXERR_INVALOUTPUT       illegal output line 
  569.  
  570. Comments    This function allows inputs to be selectively patched
  571.         to one or more outputs.  It also allows outputs to
  572.         be connected to one or more inputs.  This function
  573.         allows the caller to say "connect input lines 1, 3 and 5
  574.         to output #1" or "connect input line 4 to outputs 1 and 2"
  575.         If the hardware cannot support all connections requested,
  576.         the mixer driver will connect the lower numbered lines
  577.         first.  Calling mixGetConnections after    mixSetConnections
  578.         is recommended for verification of requested connections.
  579.  
  580. See Also     mixGetConnections
  581.         
  582.  
  583. ______________________________________________________________________
  584.  
  585.  
  586.  
  587.  
  588. // LINE CONTROLS
  589. mixGetControl        - gets the setting of a line's control
  590. mixSetControl        - sets the level of a line's control
  591. mixGetLineInfo        - gets support functionality of a line
  592.  
  593. ______________________________________________________________________
  594.  
  595. Syntax        mixGetControl(hMixer, wLineNum, dwControl, lpdwSetting);
  596.  
  597. Parameters    HMIXER    hMixer
  598.           Identifies the mixer device to be used.
  599.  
  600.         WORD      wLineNum
  601.           The low byte indicates the mixer line to get the
  602.           connections information for.
  603.           The high byte indicates whether the line is an
  604.           input line or an output line. The following 
  605.           macros (equates) are used for the high byte:
  606.               MIX_INPUT    
  607.               MIX_OUTPUT
  608.  
  609.         DWORD    dwControl
  610.           Specifies the control to get the setting of.
  611.           Here is the current list of possible controls:
  612.  
  613.               MIX_SUPPORT_LRVOLUME       left-right volume control
  614.               MIX_SUPPORT_ALC                Auto Level Control
  615.               MIX_SUPPORT_BMT                B-M-T equalization
  616.               MIX_SUPPORT_CROSSOVER      crossover change
  617.               MIX_SUPPORT_LOUDNESS       loudness equalization
  618.               MIX_SUPPORT_MUTE                channel mute
  619.               MIX_SUPPORT_REVERB     reverb 
  620.               MIX_SUPPORT_STEREOENHANCE  stereo enhance 
  621.               MIX_SUPPORT_CUSTOM1     custom effect #1
  622.               MIX_SUPPORT_CUSTOM2     custom effect #2
  623.               MIX_SUPPORT_CUSTOM3     custom effect #3
  624.  
  625.         LPDWORD lpdwSetting
  626.           Specifies a far pointer to a location that will be
  627.           filled with the current Control setting.  For
  628.           stereo controls, the high-order word of this
  629.           location contains the left channel setting and
  630.           the low-order word contains the right channel setting.
  631.           A value of 0xFFFF represents full intensity and a value
  632.           of 0x0000 is full cutout.
  633.  
  634. Return Value    Returns zero if the function was successful. 
  635.         Otherwise, it returns an error. Possible errors are:
  636.  
  637.             MIXERR_INVALINPUT        illegal input line    
  638.             MIXERR_INVALOUTPUT       illegal output line 
  639.             MIXERR_NOTSUPPORTED            control not supported     
  640.  
  641.           
  642. See Also    mixSetControl
  643. ______________________________________________________________________
  644.  
  645. Syntax        mixSetControl(hMixer, wLineNum, dwControl, dwSetting)
  646.  
  647. Parameters    HMIXER    hMixer
  648.           Identifies the mixer device to be used.
  649.  
  650.          WORD    wLineNum
  651.           The low byte indicates the mixer line to get the
  652.           connections information for.
  653.           The high byte indicates whether the line is an
  654.           input line or an output line. The following 
  655.           macros (equates) are used for the high byte:
  656.               MIX_INPUT    
  657.               MIX_OUTPUT
  658.           Specifies the input to set Control for
  659.  
  660.         DWORD    dwControl
  661.           Specifies the control to set
  662.           Here is the current list of possible controls:
  663.  
  664.               MIX_SUPPORT_LRVOLUME       left-right volume control
  665.               MIX_SUPPORT_ALC           Auto Level Control
  666.               MIX_SUPPORT_BMT           B-M-T equalization
  667.               MIX_SUPPORT_CROSSOVER      crossover change
  668.               MIX_SUPPORT_LOUDNESS       loudness equalization
  669.               MIX_SUPPORT_MUTE           channel mute
  670.               MIX_SUPPORT_REVERB           reverb 
  671.               MIX_SUPPORT_STEREOENHANCE  stereo enhance 
  672.               MIX_SUPPORT_CUSTOM1           custom effect #1
  673.               MIX_SUPPORT_CUSTOM2           custom effect #2
  674.               MIX_SUPPORT_CUSTOM3           custom effect #3
  675.  
  676.         DWORD    dwSetting
  677.           Specifies a far pointer to a location that will be
  678.           filled with the current Control setting.  For
  679.           stereo controls, the high-order word of this
  680.           location contains the left channel setting and
  681.           the low-order word contains the right channel setting.
  682.           A value of 0xFFFF represents full intensity and a value
  683.           of 0x0000 is full cutout.
  684.  
  685. Return Value    Returns zero if the function was successful. 
  686.         Otherwise, it returns an error. Possible errors are:
  687.  
  688.             MIXERR_INVALINPUT        illegal input line    
  689.             MIXERR_INVALOUTPUT       illegal output line 
  690.             MIXERR_NOTSUPPORTED       control not supported     
  691.           
  692. See Also    mixGetControl, CONTROL SETTING NOTES
  693.  
  694. _____________________________________________________________________
  695.  
  696.  
  697. Syntax        mixGetLineInfo(hMixer, wLineNum, lpInfo, wSize);
  698.  
  699.         Retrieves information about the specified input's
  700.         capabilities.
  701.  
  702. Parameters    HMIXER    hMixer
  703.           Identifies the mixer device to be used.
  704.  
  705.         WORD      wLineNum
  706.           The low byte indicates the mixer line to get the
  707.           connections information for.
  708.           The high byte indicates whether the line is an
  709.           input line or an output line. The following 
  710.           macros (equates) are used for the high byte:
  711.               MIX_INPUT    
  712.               MIX_OUTPUT
  713.  
  714.         LPMIXERLINEINFO  lpInfo
  715.           Specifiies a far pointer to be filled with the capability
  716.           information for the specified input.
  717.  
  718.         WORD  wSize    
  719.           Specifies the size of the LPMIXERLINEINFO structure.
  720.  
  721.  
  722. Return Value    Returns zero if the function was successful. 
  723.  
  724. Comments    
  725.  
  726. See Also    
  727.  
  728. ______________________________________________________________________
  729.  
  730.  
  731. // PATCH CALLS
  732. mixGetPatch        - gets a line's patch number
  733. mixSetPatch        - sets a line's patch information
  734. mixGetPatchInfo        - returns information on a standard mixerpatch
  735.  
  736. ______________________________________________________________________
  737.  
  738. Syntax        mixGetPatch(hMixer,wLineNum, lpwPatchNum);
  739.  
  740.         Returns information regarding a specific input patch
  741.         that can be selected into an input
  742.  
  743. Parameters    HMIXER    hMixer
  744.           Identifies the mixer device to be used.
  745.  
  746.         WORD      wLineNum
  747.           The low byte indicates the mixer line to get the
  748.           connections information for.
  749.           The high byte indicates whether the line is an
  750.           input line or an output line. The following 
  751.           macros (equates) are used for the high byte:
  752.               MIX_INPUT    
  753.               MIX_OUTPUT
  754.  
  755.         LPWORD    lpwPatchNum
  756.           Destination for the patch number.  A value of -1
  757.           signifies a user-defined patch.              
  758.           
  759. Return Value    Returns zero if the function was successful. 
  760.         Otherwise, it returns an error. Possible errors are:
  761.         
  762.             MIXERR_INVALINPUT        illegal input line    
  763.             MIXERR_INVALOUTPUT       illegal output line 
  764.  
  765. Comments    The range of wPatchNum must be from 0 to 1 less than
  766.         the number of software patches returned in 
  767.         mixGetDevCaps.
  768.  
  769. See Also    mixSetPatch, mixGetPatchInfo
  770.  
  771. ______________________________________________________________________
  772.  
  773. Syntax        mixSetPatch(hMixer,wLine, wPatchNum,lpPatch,wSize);
  774.  
  775.         Allows the user to set the patch of an input to
  776.         another device.  
  777.  
  778. Parameters    HMIXER    hMixer
  779.           Identifies the mixer device to be used.
  780.  
  781.         WORD      wLine
  782.           The low byte indicates the mixer line to get the
  783.           connections information for.
  784.           The high byte indicates whether the line is an
  785.           input line or an output line. The following 
  786.           macros (equates) are used for the high byte:
  787.               MIX_INPUT    
  788.               MIX_OUTPUT
  789.                                
  790.         WORD    wPatchNum
  791.           Specifies the patch number to set.  Each mixer
  792.           driver has a number of internal patches that
  793.             are selected by this parameter.    
  794.           
  795.         LPPATCHINFO lpInfo
  796.           If this parameter is not NULL, the wPatchNum
  797.           parameter is ignored and the PATCHINFO structure
  798.           pointed to is used to set the patch information.
  799.           The patch number assigned will be -1;    
  800.  
  801.         WORD    wSize
  802.           Specifies size of PATCHINFO structure
  803.  
  804.  
  805. Return Value    Returns zero if the function was successful. 
  806.         Otherwise, it returns an error. Possible errors are:
  807.           
  808.             MIXERR_INVALINPUT        illegal input line    
  809.             MIXERR_INVALOUTPUT       illegal output line 
  810.             MIXERR_PATCHMISMATCH   patch-to-line mismatch
  811.  
  812. Comments    The MIX_USER_CONNECTED bit may be OR'd with the patch
  813.         type to indicate a patch that is to be connected by
  814.         the user rather than one that is selected via
  815.         software control.  Applications should check this bit
  816.         at initialization time to advise users to make the
  817.         external connection.  If the patch number of a user-
  818.         connected patch is illegal, the driver's default
  819.         patch for that line will be used.
  820.         
  821. See Also    mixGetPatchInfo, mixGetPatch
  822. ______________________________________________________________________
  823.  
  824. Syntax        mixGetPatchInfo(hMixer,wPatchNum,lpInfo,wSize);
  825.  
  826.         Returns information about a pre-defined patch.
  827.  
  828. Parameters    HMIXER    hMixer
  829.           Identifies the mixer device to be used.
  830.  
  831.         WORD    wPatchNum
  832.           Specifies the patch number to set.  Each mixer
  833.           driver has a number of internal patches that
  834.             are selected by this parameter.
  835.           
  836.         LPPATCHINFO lpInfo
  837.           If this parameter is not NULL, the wPatchNum
  838.           parameter is ignored and the PATCHINFO structure
  839.           pointed to is used to set the patch information.
  840.  
  841.         WORD    wSize
  842.           Specifies size of PATCHINFO structure
  843.  
  844.  
  845. Return Value    Returns zero if the function was successful. 
  846.         Otherwise, it returns an error. Possible errors are:
  847.           
  848.             MIXERR_INVALPATCH        patch number out of range
  849.  
  850. Comments    The current patch information for a line is  
  851.         available by calling mixGetLineInfo.  Now that 
  852.         patch information is stored in WIN.INI, the default
  853.         patch information is automatically overridden.  In
  854.         most cases the wPatchNum will be -1.  User defined
  855.         patch information is not returned by this call.
  856.  
  857.         
  858. See Also    mixGetPatch, mixSetPatch, mixGetLineInfo
  859. ______________________________________________________________________
  860.  
  861. // DEVICE ORIENTED CALLS
  862. mixGetDeviceName    - converts device type to device name
  863. mixGetDeviceLines    - finds which lines have a specified device 
  864. mixSetDeviceConnections    - performs abstract device connection
  865. mixGetDeviceConnections - determines device types connected
  866.  
  867. ______________________________________________________________________
  868.  
  869. Syntax        mixGetDeviceName(dwDeviceType, lpDeviceName, wSize);
  870.  
  871.         Returns information regarding a specific input patch
  872.         that can be selected into an input
  873.  
  874. Parameters    DWORD    dwDeviceType
  875.           A 32-bit value indication the device type
  876.  
  877.         LPSTR    lpDeviceName
  878.           points to the destination for the device name
  879.  
  880.         WORD      wSize
  881.           buffers size pointed to by lpDeviceName    
  882.           If wSize <= MIX_DEVICESHORTNAME, the three letter
  883.           standard device mnemonic string will be copied to 
  884.           the buffer.  In all cases wSize will be the limit
  885.           of characters copied.
  886.           
  887. Return Value    Returns zero if the function was successful. 
  888.         
  889. Comments    The device short name is intended for display in
  890.         dialog boxes and in win.ini's mixer configuration
  891.         settings.  
  892.  
  893. See Also    mixGetDeviceLines, mixGetDeviceConnections
  894.  
  895. ______________________________________________________________________
  896.  
  897.  
  898. Syntax        mixGetDeviceLines(hMixer,lpDeviceLines);
  899.         
  900. ///  Given a device type, this function will report the lines that the given
  901. ///  device is connected to.  If the association is not NULL, only
  902. ///  lines with the same association will be reported.  Otherwise, all
  903. ///  devices of the given type are reported on. 
  904. ///
  905.  
  906. Parameters    HMIXER    hMixer
  907.           Identifies the mixer device to be used.
  908.  
  909.         LPDEVICELINES lpDeviceLines
  910.           far pointer to DEVICELINES data structure
  911.  
  912.         struct {
  913.         DWORD     dwDeviceType;     // aka technology
  914.         WORD    wNumDevices;     // return value: # lines with device found
  915.         DWORD    dwLines;     // return value: line map
  916.         DWORD    dwAssociation;     // for exclusive search
  917.         } DEVICELINES;
  918.  
  919. typedef DEVICELINES FAR *LPDEVICELINES;
  920.  
  921.           
  922.           
  923. Return Value    Returns zero if the function was successful. 
  924.  
  925. Comments    Be sure that the dwAssociation element of the
  926.         DEVICELINES structure is NULL unless you intend
  927.         to find a specific device line of which the
  928.         association has been established.
  929.  
  930. See Also    mixGetDeviceConnections, mixGetPatchInfo
  931.  
  932. ______________________________________________________________________
  933.  
  934. Syntax        mixGetDeviceConnections(hMixer,lpDeviceConnect);
  935.  
  936.  
  937.         Given a device type, this function will return device
  938.         types that the given device type is connected to.  
  939.         Input device types will yield reporting of output device
  940.         types connected and vice versa.  If the associationType
  941.         is given, only devices with the same association
  942.         will be reported.  Otherwise, all devices of the given
  943.         type are reported on.
  944.  
  945.  
  946. Parameters    HMIXER    hMixer
  947.           Identifies the mixer device to be used.
  948.  
  949.  
  950.         LPDEVICECONNECT    lpDeviceConnect
  951.           long pointer to DEVICECONNECT structure
  952.  
  953.         typedef struct{  
  954.         DWORD dwInputDeviceType;
  955.         DWORD dwOutputDeviceType;
  956.         DWORD dwInputAssociation;
  957.         DWORD dwOutputAssociation;
  958.         } DEVICECONNECT;
  959.  
  960.           
  961. Return Value    Returns zero if the function was successful. 
  962.         Otherwise, it returns an error. Possible errors are:
  963.         
  964.             MIXERR_INVALSTRUCTPTR  null lpDeviceConnect
  965.  
  966. Comments    An output device type is one that can be connected to
  967.         a mixer output and is distingquished by having the
  968.         MIX_LISTENER bit set in its dwDeviceType field.     
  969.  
  970. See Also    mixSetDeviceConnections
  971.  
  972. ______________________________________________________________________
  973.  
  974. Syntax        mixSetDeviceConnections(hMixer,lpDeviceConnect)
  975.  
  976.         Given two device types, input and output, this function
  977.         will attempt to connect the two types.  If the
  978.         associationType and associationValue fields are not NULL,
  979.         only devices with the same association will be
  980.         connected.  
  981.  
  982. Parameters    HMIXER    hMixer
  983.           Identifies the mixer device to be used.
  984.  
  985.         LPDEVICECONNECT    lpDeviceConnect
  986.           long pointer to DEVICECONNECT structure
  987.  
  988.         typedef struct{  
  989.         DWORD dwInputDeviceType;
  990.         DWORD dwOutputDeviceType;
  991.         DWORD dwInputAssociation;
  992.         DWORD dwOutputAssociation;
  993.         } DEVICECONNECT;
  994.  
  995.  
  996. Return Value    Returns zero if the function was successful. 
  997.         Otherwise, it returns an error. Possible errors are:
  998.         
  999.             MIXERR_INVALSTRUCTPTR  null lpDeviceConnect
  1000. Comments    
  1001.  
  1002. See Also    mixGetDeviceConnections
  1003.  
  1004. ______________________________________________________________________
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010. CONTROL SETTING NOTES
  1011.  
  1012. The functions mixGetControl and mixSetInputControl
  1013. have a dwControl parameter and a dwSetting parameter.
  1014.  
  1015. Following the example set by Microsoft's volume settings, each
  1016. control setting will have associated with it a double word value
  1017. for specifying its setting.
  1018.  
  1019. dwControl         description            format    
  1020. ---------         -----------            ------
  1021.  
  1022. MIX_SUPPORT_VOLUME     volume control               LLLL:RRRR scalar
  1023. MIX_SUPPORT_LRVOLUME       left-right volume control    LLLL:RRRR scalar
  1024. MIX_SUPPORT_ALC         Auto Level Control        LLLL:RRRR on/off
  1025. MIX_SUPPORT_BMT         B-M-T equalization        --BB:MMTT scalar
  1026. MIX_SUPPORT_CROSSOVER     crossover change             MIXCROSSCAPS
  1027. MIX_SUPPORT_LOUDNESS     loudness equalization        LLLL:RRRR on/off
  1028. MIX_SUPPORT_MUTE         mute - don't change volume    LLLL:RRRR on/off
  1029. MIX_SUPPORT_REVERB     reverb             LLLL:RRRR scalar
  1030. MIX_SUPPORT_STEREOENHANCE  stereo enhance         LLLL:RRRR on/off
  1031. MIX_SUPPORT_CUSTOM1     custom effect #1        LLLL:RRRR on/off
  1032. MIX_SUPPORT_CUSTOM2     custom effect #2        LLLL:RRRR scalar
  1033.  
  1034. Scalars are unsigned values from 0-65535 except in the case of BMT
  1035. where they are unsigned values from 0-255.  These values should be
  1036. interpolated to match the mixer hardware's scale.
  1037.  
  1038. On/Off values are ON for any non-zero value.
  1039.  
  1040. //////////////////////////////////////////////////////////////////////
  1041.  
  1042.  
  1043. MCI INTERFACE
  1044.  
  1045. Media Vision is now providing an MCI driver for controlling the mixer
  1046. hardware.  For many of you, this will make the control of mixing
  1047. functions much easier than it ever has been.
  1048.  
  1049. MCI, as you must know, stands for Media Control Interface.  In the
  1050. case of a mixer, there is no media (medium).  When we speak of 
  1051. CDs, wave files, MIDI, we connote some sort of media transport,
  1052. (ie. position within the data, support for PLAY, STOP, REWIND, etc)
  1053.  
  1054. A PLAY command sent to a mixer does not make sense.  In fact most MCI
  1055. commands have little meaning for a mixer.
  1056.  
  1057. Still, MCI is powerful.  One of its outstanding features is its
  1058. ability to convert strings into driver commands.  We have, therefore,
  1059. developed an MCI driver for Multimedia Windows.
  1060.  
  1061. The documentation for the MCI mixer is found in the file
  1062. mcimixer.doc.
  1063.  
  1064. //////////////////////////////////////////////////////////////////////
  1065.  
  1066. MIXER NOTES:
  1067.  
  1068. The mixSetState function allows timed fades.  If it would be useful
  1069. to developers we can add the capability for timed fades to the
  1070. mixSetControl function.  Let us know if you want this.  Soon.
  1071.  
  1072. User-defined patches are not accessible through mixGetPatchInfo.
  1073. The mechanism of user-defined patches may change in the future.
  1074.  
  1075.  
  1076. //////////////////////////////////////////////////////////////////////
  1077. GLOSSARY:
  1078.  
  1079. line - a stereo input or output of a mixer
  1080.  
  1081. patch - the association of a line to a particular sound producing
  1082.     or recording device
  1083.  
  1084. connection - this term refers to a mixer's internal input-to-output
  1085.      routing of an audio signal     
  1086.  
  1087. control    - the capability to modify an audio signal (ie volume)
  1088.  
  1089. cross-fade  - fading one or more controls up while fading other out
  1090.     
  1091.  
  1092.  
  1093. //////////////////////////////////////////////////////////////////////
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.